Skip to content

add docker compose section to multicontainer guide#2380

Merged
kcmartin merged 7 commits intomainfrom
add-docker-compose-multicontainer-machines-guide
Apr 17, 2026
Merged

add docker compose section to multicontainer guide#2380
kcmartin merged 7 commits intomainfrom
add-docker-compose-multicontainer-machines-guide

Conversation

@kcmartin
Copy link
Copy Markdown
Contributor

@kcmartin kcmartin commented Apr 10, 2026

Summary of changes

Add a self-contained section to add to the multi-container Machines guide. Covers config, routing, a practical nginx + Redis example, three clear limitations.

Preview

Screenshot 2026-04-10 at 4 16 53 PM

Replace the nginx + custom-build rate-limiting example with a web
service + Redis sidecar using two public images. The previous example
referenced an nginx.conf and Dockerfile that weren't shown, so readers
couldn't run it as written.
fly deploy needs at least one Dockerfile, buildpack, or image in
fly.toml to build from — a compose file with only pre-built images
fails with "app does not have a Dockerfile or buildpacks configured."
Add a minimal Dockerfile and switch the web service to build: . so
the example is runnable as written. Also tighten the limitation
wording from "only one" to "exactly one."
The example mapped container port 80 to host port 8080 in compose.yml
and set internal_port = 8080 in fly.toml, but nginxdemos/hello listens
on 80, so the Fly proxy forwarded traffic to a port nothing was
listening on. Align everything on port 80.
The [build.compose] block syntax was introduced in commit ee0ccdb
(merged 2025-07-07 19:42 UTC), which first shipped in v0.3.152
(released 2025-07-08). v0.3.149-v0.3.151 only accept the older
string-typed compose = "file.yml" field under [build] and reject
the [build.compose] block with an unmarshal error. Verified by
running fly config validate against each version.
@kcmartin kcmartin requested a review from Roadmaster April 14, 2026 22:11
Copy link
Copy Markdown
Contributor

@Roadmaster Roadmaster left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! I tested it just to see it in action and confirm these instructions work - they do, out of the box.

Thanks!

Actually - EDIT: The compose file I used here specifies volumes, but flyctl will happily ignore volume setup it seems, and this will lead to data loss (imagine someone deploys paperless-ngx using that, writes a bunch of data to the rootfs and then restarts the machine).

We don't need to hold this doc update until we figure this out, but it would perhaps be good to point out somewhere that some compose configurations are recognized and handled by flyctl and some are happily ignored.

FWIW flyctl did say something about volumes at deploy time, but it's not super clear that this means "i'm not going to create or mount these volumes for you" - in principle it could not, because a Fly machine can only have one attached volume and this configuration wants 5 volumes.

$ fly deploy --ha=false
==> Verifying app config
Warning: Could not read volume file redisdata: open redisdata: no such file or directory
Warning: Could not read volume file data: open data: no such file or directory
Warning: Could not read volume file media: open media: no such file or directory
Warning: Could not read volume file export: open export: no such file or directory
Warning: Could not read volume file consume: open consume: no such file or directory

In summary, I think just a quick warning that if your compose file specifies volumes it will need adapting by hand might be worth it.

@kcmartin kcmartin force-pushed the add-docker-compose-multicontainer-machines-guide branch from 25b2ac4 to eb3d20b Compare April 17, 2026 16:25
@kcmartin
Copy link
Copy Markdown
Contributor Author

@Roadmaster

Actually - EDIT: The compose file I used here specifies volumes, but flyctl will happily ignore volume setup it seems, and this will lead to data loss (imagine someone deploys paperless-ngx using that, writes a bunch of data to the rootfs and then restarts the machine).

In summary, I think just a quick warning that if your compose file specifies volumes it will need adapting by hand might be worth it.

Thanks for finding this. I tested and confirmed the following:

I reproduced the behavior with a volumes: declaration in the Compose file and confirmed:

  • fly deploy prints Warning: Could not read volume file... multiple times but succeeds
    anyway.
  • Data written to the path intended for the volume lives on an ephemeral overlay — it's
    wiped on both fly machine restart and subsequent fly deploy runs.

I've added a warning callout just above the Limitations section pointing this out and directing readers to Fly Volumes + [mounts] for persistent storage.

@Roadmaster
Copy link
Copy Markdown
Contributor

LGTM thanks! ship it!

@kcmartin kcmartin merged commit 28aca09 into main Apr 17, 2026
1 of 2 checks passed
@kcmartin kcmartin deleted the add-docker-compose-multicontainer-machines-guide branch April 17, 2026 17:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants